docs: repoint 5 dangling section references to their current sections - #179

Summary

Repoint the 5 section references in tracked files that point at headings which no longer exist.

The 2026-08-22 docs flattening (6d87213, "concise current-state docs") cut docs/architecture.md from 18 headings to 9 — deleting the entire 4.x subsection layer — and docs/user-stories.md from 14 headings to 5. Five references have cited dead headings ever since, and nothing in the repo notices: a maintainer reading src/router.rs gets no signal that its citation is stale.

src/db.rs:3 (architecture §5) already resolves and is deliberately left untouched — a blanket "delete every section reference" pass would have destroyed the only live one.

Each target was read at HEAD before repointing, and each now cites a section that actually contains the content. The old numbering is kept in the two places where it still carries meaning (router.rs and ui/README.md), because the surviving document no longer has subsections, so the reader has no other way to connect the two.

Related Issue

No issue exists for this — the defect was found by scanning the repository itself, not reported. Leaving this empty rather than fabricating a reference.

Changes

• Repoint 5 dangling section references (src/router.rs, src/billing.rs, src/gateway.rs, ui/README.md)
• Comment/doc-only: zero production behaviour change, zero i18n keys, no cache-bust, no config/data structure touched
• src/db.rs:3 left as-is (it resolves)

Tests

• cargo test — 165 passed / 0 failed
• cargo fmt --check — clean
• cargo clippy --all-targets -- -D warnings — clean, 0 warnings
• Reference resolver, before vs after: 1 of 6 → 6 of 6 resolving

The resolver walks every § occurrence in tracked files and resolves it against the current heading set of the document it names. It carries panicking positive controls (the heading extractor must find docs/architecture.md §1/§5 and docs/user-stories.md §4, or it aborts rather than reporting a vacuous "clean"), and it is proven non-vacuous by running it against the pre-flatten tree (6d87213^), where the same references resolve 8 of 8 — i.e. the "rot" is real and the tool can see both states. No unit test was added: this is a documentation/comment fix with no behaviour to assert, and the repo deliberately carries no doc-linting toolchain (same call as #178).

Checklist

• Branch naming follows convention (docs/)
• Commit message uses Conventional Commits (docs: — no single scope spans three src/ modules plus ui/)
• Single responsibility, minimal change (5 lines across 4 files)